docs(spec): point ActionSchema.method's worked example at the shipped data door - #15098

Fixes #14093

Clause ②: no — path limb fires (packages/spec/src/**), content limb no: comment text only

What was wrong

ActionSchema.method's TSDoc carried the only worked example of a type: 'api' PATCH
against the data API, and it pointed at /api/v1/sys_api_key/{id} — a path the router
never mounts. The /data segment was missing. Nothing catches the difference at
authoring time: objectstack validate does not check target, type: 'api' has no
author-time route validation, so the action parses green, renders, is clickable, and
404s at the click.

The two readings this correction stands on, cited on the tree at 6665c5c9

1. The shipped data door composes to PATCH /api/v1/data/:object/:id.

packages/rest/src/rest-server.ts:7664, inside registerCrudEndpoints:

const dataPath = `${basePath}${crud.dataPrefix}`;

registered at packages/rest/src/rest-server.ts:7913-7914:

method: 'PATCH',
path: `${dataPath}/:object/:id`,

basePath is getApiBasePath() (rest-server.ts:3637-3640 — api.apiPath ?? api.basePath + '/' + api.version), and crud.dataPrefix defaults to /data at
packages/spec/src/api/rest-server.zod.ts:252:

dataPrefix: z.string().default('/data').describe('URL prefix for data endpoints'),

2. Under required scoping, only the scoped path is registered.

packages/rest/src/rest-server.ts:3717-3722, in registerRoutes():

if (enableProjectScoping) {
    const scopedBase = this.getScopedBasePath(basePath);
    if (projectResolution === 'required') {
        // Strict: only scoped routes
        registerForBase(scopedBase);

with getScopedBasePath at :3646-3647 returning `${basePath}/environments/:environmentId`. So a correctly spelled unscoped full path still 404s on such a host — which is why the example now names the premise instead of promising a host-independent path.

A third reading fixes the placeholder spelling: target's own docblock at
packages/spec/src/ui/action.zod.ts:992-997 documents ${param.X} and ${ctx.X}
interpolation and names ctx.recordId explicitly. A bare {recordId} is newTabUrl's
convention alone.

The change — one docblock, verbatim

Before:

  /**
   * HTTP method to use when `type: 'api'`. Defaults to `POST`. Use `PATCH` to
   * call data-API update endpoints (e.g. `/api/v1/sys_api_key/{id}` with
   * `bodyExtra: { revoked: true }`).
   */

After:

  /**
   * HTTP method to use when `type: 'api'`. Defaults to `POST`. Use `PATCH` to
   * call data-API update endpoints. The shipped data door is
   * `PATCH {apiBase}/data/:object/:id` — `getApiBasePath()` + `crud.dataPrefix`,
   * i.e. `/api/v1` + `/data` on a default host — so the endpoint for one
   * record is e.g. `/api/v1/data/sys_api_key/${ctx.recordId}` with
   * `bodyExtra: { revoked: true }`. Two things the path depends on: the
   * `/data` segment (omit it and the action renders, is clickable, and 404s
   * at the click), and the `${ctx.X}` / `${param.X}` interpolation
   * {@link target} documents — a bare `{recordId}` placeholder is
   * {@link newTabUrl}'s convention alone and is not substituted here.
   *
   * The full path is host-dependent: under `enableProjectScoping` with
   * `projectResolution: 'required'` only
   * `/api/v1/environments/:environmentId/data/:object/:id` is registered, so
   * an unscoped path 404s on such a host — write `target` against the base
   * the host actually mounts.
   *
   * To write a field on the CURRENT record, prefer the declarative
   * {@link operation} `'update'` with {@link patch}: the platform performs
   * the write, so there is no endpoint, method or id placeholder to spell at
   * all. The `type: 'api'` + `PATCH` form above remains the way to call an
   * explicit endpoint.
   */

sys_api_key is deliberately kept — the defect was the path STRUCTURE, not which object
the example picks. No .describe() text moves, no schema member moves, and no other
member of action.zod.ts is touched (the operation / patch block from PR #15077
included). packages/rest and packages/runtime are read-only inputs here.

Deviation from the dispatch: a patch changeset, not skip-changeset

The dispatch expected skip-changeset on the premise "comment text; no published
artifact moves". Measured on the built tree, that premise does not hold, so AGENTS.md
governs and this PR carries a @objectstack/spec patch changeset instead:

• packages/spec/package.json files ships dist and src/**/*.zod.ts.
• The corrected docblock is present in 13 .js and 13 .mjs bundles under
  packages/spec/dist/ after a build (e.g. dist/ui/index.mjs:8045-8072), and in the
  shipped src/ui/action.zod.ts itself.
• So the diff publishes changed bytes from a released package (17.2.0). AGENTS.md's
  Post-Task Checklist §3 reserves that for a patch changeset and refuses
  skip-changeset for it by name: that label "is for a diff that publishes nothing from
  any released package."

Measured counterpoint, recorded because it is the surface most people assume: the
docblock reaches no .d.ts — 0 hits, and 0 for two control docblocks in the same
file as well, so this package emits no TSDoc into its declarations at all. IDE hover
text is unchanged; the npm tarball's bytes are not.

⚠️ This is a deviation from the dispatch text and is flagged rather than taken silently.
If the PM prefers the label, the changeset is one file to delete.

Verification record — all at final head b5bceb76

Every exit code captured before any pipe; verdict lines quoted from the gates themselves.

The union was re-derived at final head b5bceb76 and is byte-identical to the
derivation taken before the changeset landed — same 54 commands, same 2 paths.

The one NOT MEASURED gate, listed as such rather than as a pass:

• node scripts/check-test-completeness.mjs — exit 3, structurally unrunnable
  locally. Its own text: "this gate grades a saved turbo run test log, and no log was
  named … the local reading for this gate is NOT MEASURED. ⛔ It is not a red, and there
  is nothing here to fix." CI tees the log and passes the path, so CI measures it.

Three further gates first returned a prerequisite code and were converted into real
measurements by building rather than being written off:
check-dev-prereqs.mjs (exit 1 → 0 after pnpm build: ✓ 67 package build artifacts present),
check:doc-formula-expressions (exit 3 → 0 after building @objectstack/formula then @objectstack/lint),
and check:dual-build-cjs-loads (exit 3 → 0: 102 published require entry point(s) across 66 package(s) load).

Reverse verification is not owed for a comment-only change; the before/after docblock
above and the two cited route readings stand in its place.

Notes for the reviewer

• Draft on purpose, and left in draft: this seat does not flip to ready.
• No needs:contract-review label is applied.
• One out-of-scope finding was filed rather than fixed here — see the report comment on ActionSchema.method's worked example points a type: 'api' PATCH at /api/v1/sys_api_key/{id} — the shipped data API is /api/v1/data/:object/:id, so copying it 404s #14093.

Generated by Claude Code

Generated by Claude Code